Inside Macintosh: QuickTime Components

The Decompression Parameters Structure

Decompressors accept the parameters that govern a decompression operation in the form of a data structure. This data structure is called a decompression parameters structure . It is used by the ImageCodecBandDecompress and ImageCodecPreDecompress functions.

The decompression parameters structure is defined by the CodecDecompressParams data type as follows:



 
typedef struct {

    ImageSequence                   sequenceID;             /* unique sequence ID

                                                                (predecompress,

                                                                band decompress) */

    ImageDescriptionHandle          imageDescription;       /* handle to image description

                                                                structure (predecompress,

                                                                band decompress) */

    Ptr                             data;                   /* compressed image data */

    long                            bufferSize;             /* size of data buffer */

    long                            frameNumber;            /* frame identifier */

    long                            startLine;              /* starting line for band */

    long                            stopLine;               /* ending line for band */

    long                            conditionFlags;         /* condition flags */

    CodecFlags                      callerFlags;            /* control flags */

    CodecCapabilitiesPtr            *capabilities;          /* pointer to compressor 

                                                                capability structure

                                                                (predecompress,

                                                                band decompress) */

    ProgressProcRecord              progressProcRecord;         

                                                            /* progress function 

                                                                structure */

    CompletionProcRecord            completionProcRecord;

                                                            /* completion function 

                                                                structure */

    DataProcRecord                  dataProcRecord;         /* data-loading function 

                                                                structure */

    CGrafPtr                        port;                   /* pointer to color

                                                                graphics port for image

                                                                (predecompress,

                                                                band decompress) */

    PixMap                          dstPixMap;              /* destination pixel map

                                                                (predecompress,

                                                                band decompress) */

    BitMapPtr                       maskBits;               /* update mask */

    PixMapPtr                       mattePixMap;            /* blend matte pixel map */

    Rect                            srcRect;                /* source rectangle

                                                                (predecompress,

                                                                band decompress) */

    MatrixRecordPtr                 *matrix;                /* pointer to matrix structure

                                                                (predecompress,

                                                                band decompress) */

    CodecQ                          accuracy;               /* desired accuracy

                                                                (predecompress,

                                                                band decompress) */

    short                           transferMode;           /* transfer mode(predecompress,

                                                                band decompress) */

    long                            reserved[2];            /* reserved */

} CodecDecompressParams;



 
typedef CodecDecompressParams *CodecDecompressParamsPtr;

sequenceID: Contains the unique sequence identifier. If the image to be decompressed is part of a sequence, this field contains the sequence identifier that was assigned by the Image Compression Manager's DecompressSequenceBegin function. If the image is not part of a sequence, this field is set to 0.
imageDescription: Contains a handle to the image description structure that describes the image to be decompressed.
data: Points to the compressed image data. This must be a 32-bit clean address. The bufferSize field indicates the size of this data buffer. If the entire compressed image does not fit in memory, the application should provide a data-loading function, identified by the dataProc field of the data-loading function structure stored in the dataProcRecord field.; This field is used only by the ImageCodecBandDecompress function.
bufferSize: Specifies the size of the image data buffer.; This field is used only by the ImageCodecBandDecompress function.
frameNumber: Contains a frame identifier. Indicates the relative frame number within the sequence. The Image Compression Manager increments this value for each frame in the sequence.; This field is used only by the ImageCodecBandDecompress function.
startLine: Specifies the starting line for the band. This field indicates the starting line number for the band to be decompressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row in the image is row number 0.; This field is used only by the ImageCodecBandDecompress function.
stopLine: Specifies the ending line for the band. This field indicates the ending line number for the band to be decompressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row is row number 0.; The image band includes the row specified by this field. So, to define a band that contains one row of pixels at the top of an image, you set the startLine field to 0 and the stopLine field to 1.; This field is used only by the ImageCodecBandDecompress function.
conditionFlags: Contains flags that identify the condition under which your component has been called (in order to save the component some work). The flags in this field are passed to the component in the ImageCodecBandCompress and ImageCodecPreDecompress functions when conditions change to save it some work. In addition, these fields contain information about actions taken by your component. Condition flags fields contain the following flags:



 
                                    #define codecConditionFirstFrame                    (1L<<2)                         

                                    #define codecConditionNewDepth                      (1L<<3)     

                                    #define codecConditionNewTransform                  (1L<<4)     

                                    #define codecConditionNewSrcRect                    (1L<<5)     

                                    #define codecConditionNewMatte                      (1L<<7)         

                                    #define codecConditionNewTransferMode               (1L<<8)     

                                    #define codecConditionNewClut                       (1L<<9)     

                                    #define codecConditionNewAccuracy                   (1L<<10)    

                                    #define codecConditionNewDestination                (1L<<11)    

                                    #define codecConditionCodecChangedMask              (1L<<31)

The codecConditionFirstBand constant is an input flag that indicates if this is the first band in the frame. If this flag is set to 1, then your component is being called for the first time for the current frame.; The codecConditionLastBand constant is an input flag that indicates if this is the last band in the frame. If this flag is set to 1, then your component is being called for the last time for the current frame. If the codecConditionFirstBand flag is also set to 1, this is the only time the Image Compression Manager is calling your component for the current frame.; The codecConditionFirstFrame constant is an input flag that indicates that this is the first frame to be decompressed for this image sequence.; The codecConditionNewDepth constant is an input flag that indicates that the depth of the destination has changed for this image sequence.; The codecConditionNewTransform constant is an input flag that indicates that the transformation matrix has changed for this sequence.; The codecConditionNewSrcRect constant is an input flag that indicates that the source rectangle has changed for this sequence.; The codecConditionNewMatte is an input flag that indicates that the matte pixel map has changed for this sequence.; The codecConditionNewTransferMode constant is an input flag that indicates that the transfer mode has changed for this sequence.; The codecConditionNewClut constant is an input flag that indicates that the color lookup table has changed for this sequence.; The codecConditionNewAccuracy constant is an input flag that indicates to the component that the accuracy parameter has changed for this sequence.; The codecConditionNewDestination constant is an input flag that indicates to the component that the destination pixel map has changed for this sequence.; The codecConditionCodecChangedMask constant is an output flag that indicates that the component has changed the mask bits. If your image decompressor component can mask decompressed images and if some of the image pixels should not be written to the screen, set the corresponding bits in the mask (defined by the maskBits field in the decompression parameter structure) to 0. In addition, set this flag to 1. Otherwise, set this flag to 0.
callerFlags: Contains flags providing further control information. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information about the Image Compression Manager function control flags. Four flags are available:; The codecFlagUpdatePrevious flag controls whether your compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed. If this flag is set to 1, your compressor should copy the current frame into the previous frame buffer at the end of the frame- compression sequence. Use the source image.; The codecFlagWasCompressed flag indicates to your compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. This flag is set to 1 to indicate that the image was previously compressed. This flag is set to 0 if the image was not previously compressed.; The codecFlagUpdatePreviousComp flag controls whether your compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression. If this flag is set to 1, your compressor should update the previous frame buffer at the end of the frame compression sequence, allowing your compressor to perform frame differencing against the compression results. Use the image that results from the compression operation. If this flag is set to 0, your compressor should not modify the previous frame buffer during compression.; The codecFlagLiveGrab flag indicates whether the current sequence results from grabbing live video. When working with live video, your compressor should operate as quickly as possible and disable any additional processing, such as compensation for previously compressed data. This flag is set to 1 when you are compressing from a live video source. This field is used only by the ImageCodecBandCompress function.
capabilities: Points to a compressor capability structure (described on The Compressor Capability Structure ). The Image Compression Manager uses this parameter to determine the capabilities of your decompressor component.; This field is used only by the ImageCodecPreDecompress function.
progressProcRecord: Contains a progress function structure. During the decompression operation, your decompressor may occasionally call a function that the application provides in order to report your progress (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about progress functions). This field contains a structure that identifies the progress function. If the progressProc field of this structure is set to nil , the application did not provide a progress function.; The progress function structure is defined by the progressProcRecord data type as follows:



 
                    struct ProgressProcRecord {

                        ProgressProcPtr progressProc;            /* pointer to

                                                                     progress

                                                                     function */

                        long                 progressRefCon;/*       reference

                                                                     constant */

                    };

                typedef struct ProgressProcRecord ProgressProcRecord;

                typedef ProgressProcRecord *ProgressProcRecordPtr;

This field is used only by the ImageCodecBandDecompress function.
completionProcRecord: Contains a completion function structure. This field governs whether you perform the decompression asynchronously. If the completionProc field in this structure is set to nil , perform the decompression synchronously. If this field is not nil , it specifies an application completion function. Perform the decompression asynchronously and call that completion function when your component is finished. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information on calling completion functions. If this field has a value of -1, perform the operation asynchronously but do not call the application's completion function.; The completion function structure is defined by the CompletionProcRecord data type as follows:



 
                    struct CompletionProcRecord {

                     CompletionProcPtr completionProc;              /* pointer to

                                                                        completion

                                                                        function */

                     long                   completionRefCon;       /* reference

                                                                        constant */

                    };

            typedef struct CompletionProcRecord CompletionProcRecord;

            typedef CompletionProcRecord *CompletionProcRecordPtr;

This field is used only by the ImageCodecBandDecompress function.
dataProcRecord: Contains a data-loading function structure. If the data stream is not all in memory, your component may call an application function that loads more compressed data (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about data-loading functions). This field contains a structure that identifies that data-loading function. If the application did not provide a data-loading function, the dataProc field in this structure is set to nil . In this case, the entire image must be in memory at the location specified by the data field.; The data-loading function structure is defined by the dataProcRecord data type as follows:



 
                    struct DataProcRecord {

                        DataProcPtr dataProc;       /* pointer to data-loading

                                                        function */

                        long dataRefCon;            /* reference constant */

                    };

                    typedef struct DataProcRecord DataProcRecord;

                    typedef DataProcRecord *DataProcRecordPtr;

This field is used only by the ImageCodecBandDecompress function.
port: Points to the color graphics port that receives the decompressed image.
dstPixMap: Points to the pixel map where the decompressed image is to be displayed. The GDevice global variable is set to the destination graphics device.; The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.
maskBits: Contains an update mask. If your component can mask result data, use this mask to indicate which pixels in the destination pixel map to update. Your component indicates whether it can mask with the codecCanMask flag in the flags field of the compressor capability structure referred to by the capabilities field. This field is updated in response to the ImageCodecPreDecompress request. See "The Compressor Capability Structure," for a description of the compressor capability structure.; If the mask has not changed since the last ImageCodecBandDecompress request, the codecConditionCodecChangedMask flag in the conditionFlags field is set to 0.; This field is used only by the ImageCodecBandDecompress function.
mattePixMap: Points to a pixel map that contains a blend matte. The matte can be defined at any supported pixel depth--the matte depth need not correspond to the source or destination depths. The matte must be in the coordinate system of the source image. If the application does not want to apply a blend matte, this field is set to nil .; The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.; This field is used only by the ImageCodecBandDecompress function.
srcRect: Points to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by the width and height fields of the image description structure referred to by the imageDescription field.
matrix: Points to a matrix structure that specifies how to transform the image during decompression.
accuracy: Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values.
transferMode: Specifies the QuickDraw transfer mode for the operation. For details on QuickDraw's transfer modes, see the chapter "Basic QuickDraw" in Inside Macintosh: Imaging .
reserved: Reserved for use by Apple.

Previous | Overview | Contents | Next